/* RemoteObjectsRegistry.java    0.0.1    Nov 3, 2009
 * 
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */
package org.mentalsmash.tazio.net.ril;

import org.mentalsmash.tazio.net.ril.exceptions.NoSuchRemoteObjectException;
import org.mentalsmash.tazio.net.ril.exceptions.OIDAlreadyInUseException;
import org.mentalsmash.tazio.commons.identifiers.OID;
/**
 * This class is responsible for keeping a local registry of all the instances
 * that are exposed for remote method invocation from other hosts. It provides
 * method to add/remove such instances and get the list of the ones currently
 * registered.
 * 
 * 
 * @version 0.0.1 Nov 3, 2009
 * @author Andrea Sorbini <as@mentalsmash.org>
 * 
 */
public interface RemoteObjectsRegistry {
	/**
	 * Registers a new instance for remote method invocation with the
	 * {@link OID} provided.
	 * 
	 * @param oid
	 *            the {@link OID} that will identify the registered instance
	 * @param obj
	 *            the instance to register
	 * @throws OIDAlreadyInUseException
	 *             if the supplied OID is already being used by some other
	 *             instance in the local registry
	 */
	public void registerObject(OID oid, Object obj)	throws OIDAlreadyInUseException;

	/**
	 * Retrieves a {@link RemoteObject} proxy for the instance identified by the
	 * supplied OID.
	 * 
	 * @param oid
	 *            an OID identifying an instance registered in the local
	 *            registry.
	 * @return a {@link RemoteObject} referencing the local instance identified
	 *         by the supplied OID
	 * @throws NoSuchRemoteObjectException
	 *             if no instance in the local registry is identified by the
	 *             supplied OID;
	 */
	public RemoteObject getRemoteObject(OID oid) throws NoSuchRemoteObjectException;
	
	/**
	 * Checks whether an instance identified by the provided {@link OID} is
	 * present in the local registry or not.
	 * 
	 * @param oid
	 *            an OID identifying an instance registered in the local
	 *            registry.
	 * @return true if an instance with that OID has been registered in the
	 *         local registry
	 */
	public boolean hasObject(OID oid);
	
	/**
	 * Removes the instance identified by the passed OID from the ones available
	 * for remote method invocation from other hosts.
	 * 
	 * @param oid
	 *            an OID identifying an instance registered in the local
	 *            registry.
	 * @throws NoSuchRemoteObjectException
	 *             if no instance was found for the supplied OID.
	 */
	public void unregisterObject(OID oid) throws NoSuchRemoteObjectException;
	
	/**
	 * 
	 * @return an array containing {@link RemoteObject}s for all the instances
	 *         registered in the local registry.
	 */
	public RemoteObject[] getRegisteredObjects();
	
	/**
	 * 
	 * @return an array containing the {@link OID}s of all the instances
	 *         registered in the local registry.
	 */
	public OID[] getRegisteredOIDs();
	
	/**
	 * Checks is an instance has been registered for remote method invocation in
	 * the local registry and return its OID if that's the case.
	 * 
	 * @param obj
	 *            an Object instance
	 * @return the OID which the instance has been registered with or null if
	 *         the supplied instance hasn't been made available to remote method
	 *         invocation.
	 */
	public OID getOID(Object obj);
	
	/**
	 * Invokes a method on the registered instance identified by the passed OID
	 * and with the supplied arguments. If any exception is raised during this
	 * process, it is returned as the method's return value.
	 * 
	 * @param oid
	 *            an OID identifying a local instance
	 * @param rm
	 *            a {@link RemoteMethod} identifying the method to invoke
	 * @param args
	 *            the arguments for the method
	 * @return the method's invocation result value or the exception thrown by
	 *         it
	 */
	public Object invokeMethod(OID oid, RemoteMethod rm, Object[] args) throws NoSuchRemoteObjectException;
	
//	/**
//	 * Sets the RemoteInvoker this RemoteObjectsRegistry is currently working with. 
//	 * @param invoker
//	 */
//	void setRemoteInvoker(RemoteInvoker invoker);
}
